home *** CD-ROM | disk | FTP | other *** search
/ Graphics Plus / Graphics Plus.iso / general / hdf / docs / hdfvset.lha / HDFVset.ch5 < prev    next >
Text File  |  1994-01-10  |  11KB  |  424 lines
  1. 5.1    NCSA HDF Vset
  2.  
  3. Vdata Routine Descriptions    5.1
  4.  
  5. National Center for Supercomputing Applications
  6.  
  7. November 1990
  8.  
  9.                                                                
  10.  
  11.  
  12.  
  13.  
  14. 5.1    NCSA HDF Vset
  15.  
  16. Vdata Routine Descriptions    5.1
  17.  
  18. National Center for Supercomputing Applications
  19.  
  20. November 1990
  21.  
  22.                                                                 
  23.  
  24. March 1990
  25.  
  26.  
  27.  
  28.  
  29. Chapter  5    Vdata Routine Descriptions
  30.  
  31.  
  32.  
  33. Chapter Overview
  34. VSattach
  35. VSdetach
  36. VSfdefine
  37. VSfexist
  38. VSgetclass
  39. VSgetid
  40. VSgetname
  41. VSinquire
  42. VSlone
  43. VSread
  44. VSseek
  45. VSsetclass
  46. VSsetfields
  47. VSsetinterlace
  48. VSsetname
  49. VSwrite
  50.  
  51. Chapter Overview
  52.  
  53. This chapter describes the vdata routines in the C library in detail.
  54.  
  55.  
  56. VSattach
  57. (VDATA*) VSattach   (f, vsid, access)
  58.  
  59.     VGROUP    *vg;
  60.     int    vsid;
  61.     character    *access;
  62.  
  63. Purpose:  This access routine attaches to the vdata that has id vsid 
  64. within the opened HDF file (pointer f) and then returns a pointer to 
  65. that vdata.
  66.  
  67. Specifics:  Access is either "r" (read) or "w" (write). Currently, 
  68. you may only write to a new vdata (by specifying vsid = -1). You 
  69. may not attach to any existing vdata for writing or appending new 
  70. data to it. The default interlace for a vdata attached with "w" access 
  71. is FULL_INTERLACE (Use VSsetinterlace to modify the 
  72. interlace).
  73.  
  74. If access is "r", vsid must be a valid id of an existing vdata as 
  75. returned  from any of the search routines (Vgetnext or VSgetid).
  76.  
  77. Return value:  If the attach is successful, a vdata pointer is 
  78. returned; otherwise, NULL is returned.
  79.  
  80.  
  81. VSdetach
  82. (void) VSdetach   (vs)
  83.  
  84.     VDATA    *vs;
  85.  
  86. Purpose:  This access routine detaches vs,  the vdata that was 
  87. currently attached, terminating further access to that vdata.
  88.  
  89. Specifics:  VSdetach updates the vdata information in the HDF file 
  90. if there are any changes. All memory used for that vdata is freed. 
  91. The pointer vs should not be used after that vdata is detached.
  92.  
  93. Return value:  None.
  94.  
  95.  
  96.  
  97. VSfdefine
  98. int VSfdefine   (vs, field, fieldtype, order)
  99.  
  100.     VDATA    *vs;
  101.     char    *field;
  102.     int    fieldtype;
  103.     int    order;
  104.  
  105. Purpose:  This specify routine is used to define a new, or 
  106. unsupported field for which you have data to be written to that 
  107. vdata. (See the description of VSsetfields for more details about 
  108. such fields.) 
  109.  
  110. Specifics:  VSfdefine is used only on a vdata that has "w" access.
  111.  
  112. You specify a field by naming it as a character string in field, its 
  113. type in fieldtype, and its order in order.
  114.  
  115.     The type may be one of the following:
  116.  
  117.         LOCAL_FLOATTYPE    for float type
  118.         LOCAL_INTTYPE    for integer type
  119.         LOCAL_BYTETYPE    for byte type
  120.         LOCAL LONGTYPE    for long integer type
  121.  
  122. Note that an integer is stored as 2 bytes in the HDF file while a long 
  123. integer is stored as 4 bytes. A float is stored as 4 bytes.
  124.  
  125. The order of a field is the number of units of data type (float, int, 
  126. byte, or long) it comprises.
  127.  
  128. For instance, a field called VECTOR comprising 3 floats may be 
  129. defined by the call as follows:
  130.  
  131.     VSfdefine(vs,VECTOR,LOCAL_FLOATTYPE,3);
  132.  
  133. Only one field may be defined per call.
  134.  
  135. NOTE:  Defining a field using VSfdefine does not prepare the 
  136. storage format of the vdata. To do so, use VSsetfields.
  137.  
  138. Return value:  Upon success, 1 is returned; otherwise, -1 is 
  139. returned.
  140.  
  141.  
  142. VSfexist
  143. int VSfexist   (vs, fields)
  144.  
  145.     VDATA    *vs;
  146.     char    *fields;
  147.  
  148. Purpose:  This inquiry routine checks whether all the field(s) 
  149. specified in fields exists in the vdata vs. 
  150.  
  151. Specifics:  The fields argument is a string of comma-separated 
  152. fieldnames (e.g., PX, PY, PZ).
  153. Return value:  A value of 1 is returned if all field(s) exist; 
  154. otherwise -1 is returned
  155.  
  156.  
  157. VSgetclass
  158. (void) VSgetclass   (vs,vsclass)
  159.  
  160.     VDATA        *vs;
  161.     char        *vsclass;
  162.  
  163. Purpose:  This inquiry routine returns in vsclass the class field 
  164. name (if any) of the vdata `.
  165.  
  166. Return value:  None.
  167.  
  168.  
  169. VSgetid
  170. int VSgetid   (f, vsid)
  171.  
  172.     DF    *f;
  173.     int    vsid;
  174.  
  175. Purpose:  This search routine searches through the HDF file and 
  176. returns the id of the next vdata after the vdata that has id vsid.
  177.  
  178. Specifics:  To initiate a search, call this routine with a value of -1 
  179. for vsid. Doing so returns the id of the first vdata in the file.
  180.  
  181. Return value:  Upon success, the id (0 or the integer) if the next 
  182. vdata is returned. On error, or when there are no more vdatas, -1 is 
  183. returned.
  184.  
  185.  
  186. VSgetname
  187. (void) VSgetname   (vs, vsname)
  188.  
  189.     VDATA    *vs;
  190.     char    *vsname;
  191.  
  192. Purpose:  This inquiry routine returns in vsname the name (if 
  193. any) of the vdata vs.
  194.  
  195. Return value:  None.
  196.  
  197.  
  198. VSinquire
  199. int VSinquire   (vs, nelements, interlace, 
  200. fields, vsize, vsname)
  201.  
  202.     VDATA    *vs;
  203.     char    *fields;
  204.     char    *vsname;
  205.     int    *vsize;
  206.     int    *interlace;
  207.     int    *nelements;
  208.  
  209. Purpose:  VSinquire is the general vdata inquiry routine.
  210.  
  211. Specifics:  Given a vdata vs, VSinquire returns the following 
  212. information about that vdata:
  213.  
  214. Ñ    nelements    the number of elements in vs
  215.  
  216. Ñ    interlace    the type of interlace: FULL_INTERLACE or     
  217.         NO_INTERLACE
  218.  
  219. Ñ    vsize    the size in bytes of an element in vs
  220.  
  221. Ñ    fields    a comma-separated string listing all fields     
  222.         in vs (e.g., "PX, PY, PZ")
  223.  
  224. Ñ    vsname    the name (if any) of vs
  225.  
  226. Return value:  Upon success, 1 is returned; otherwise, -1.
  227.  
  228.  
  229. VSlone
  230. int VSlone   (f, idarray, asize)
  231.  
  232. DF        *f;
  233. int        idarray [ ];
  234. int        asize;
  235.  
  236. Purpose:  This inquiry routine returns an array of reference 
  237. numbers of all vdatas that are not linked to any vgroup in the HDF 
  238. file.
  239.  
  240. Specifics:  You must provide the integer array idarray, and you 
  241. must specify the integer size of the array in the argument asize. 
  242. The return value from this function will be the total number of 
  243. vdatas that are not linked to any vgroup in the file. But at most  
  244. asize reference numbers will be returned in idarray.
  245.  
  246. An array size of 65000 integers for idarray will be usually more 
  247. than adequate. To use dynamic memory instead, first call VSlone 
  248. with a small value (e.g., 0 or 1) for asize, and then use the 
  249. returned value to allocate memory for idarray to be passed to a 
  250. subsequent call to VSlone.
  251.  
  252. Return value:  If there is an error, the return value is -1. 
  253. Otherwise, it returns the total number of all vdatas in the file that 
  254. are not linked to any vgroup.
  255. VSread
  256. int VSread   (vs, databuf, nelements, interlace)
  257.  
  258.     VDATA    *vs;
  259.     int    interlace;
  260.     int    nelements;
  261.     unsigned char    *databuf;
  262.  
  263. Purpose:  VSread is the only read routine of the HDF Vset 
  264. interface.
  265.  
  266. Specifics:  Given a vdata vs (with "r" access), and a buffer, 
  267. databuf, this routine returns the data read from that vdata in the 
  268. buffer. 
  269.  
  270. You must specify in nelements the number of elements' worth of 
  271. data to be read, and the buffer interlace in interlace. (Specify 
  272. either NO_INTERLACE or FULL_INTERLACE).
  273.  
  274. If the call is successful, the data returned in databuf is laid out as 
  275. specified by interlace, and the data fields appear in the order 
  276. specified in the last call to VSsetfields  for that vdata. 
  277.  
  278. It is an error to read from a vdata without first calling 
  279. VSsetfields on that vdata.
  280.  
  281. Return value:  The routine returns  the number of elements read, if 
  282. successful; otherwise -1 is returned.
  283.  
  284.  
  285. VSseek
  286. int VSseek   (vs,element)
  287.  
  288.     VDATA    *vs;
  289.     int    element;
  290.  
  291. Purpose:  This access routine moves the read pointer within the 
  292. vdata vs to the element  specified by vertex. The next VSread 
  293. begins at this element position. For instance, specify element = 0 
  294. to seek to the first element; element = 1 to seek the second element, 
  295. etc.
  296.  
  297. Specifics:  VSseek provides a mechanism for random-access 
  298. reads within a vdata. Each seek is constrained to an element 
  299. boundary within the vdata. The routine works for both fully- and 
  300. non-interlaced vdatas.
  301.  
  302. NOTE:  This routine may only be used with a vdata attached with 
  303. "r" access.
  304.  
  305. Return value:  The element position (i.e., zero or a positive  
  306. integer) is returned if the seek is successful. Otherwise, -1 is 
  307. returned.
  308.  
  309.  
  310. VSsetclass
  311. (void) VSsetclass   (vs,   vsclass)
  312.  
  313.     VDATA        *vs;
  314.     char        *vsclass;
  315.  
  316. Purpose:  This specify routine associates the class field name 
  317. vsclass with the vdata vs.
  318.  
  319. Specifics:  Vdatas initially have a class name of NULL. The class 
  320. name may be reset more than once.
  321.  
  322. Return value:  None.
  323.  
  324.  
  325. VSsetfields
  326. int VSsetfields   (vs, fields)
  327.  
  328.     VDATA    *vs;
  329.     char    *fields;
  330.  
  331. Purpose:  This specify routine establishes the fields to be accessed 
  332. within the vdata vs by any subsequent read or write routine 
  333. (VSread or VSwrite). The fields are specified by the string 
  334. argument fields, a comma-separated list of fieldnames 
  335. (e.g. "PX,PY,PZ").
  336.  
  337. Specifics:  The fieldnames allowed depends on the access of the 
  338. vdata:
  339.  
  340. Ñ    If access is "r", the fieldnames must be one of the names of the 
  341.     fields that already existed for that vdata. 
  342.  
  343. Ñ    If access is "w", the fieldnames can be one of the following:
  344.  
  345.     (1) Pre-defined  fieldnames  (See Appendix C "Pre-defined 
  346.     Fieldnames," for a list of pre-defined fieldnames.)
  347.  
  348.     (2) Any fieldname that has been user-defined.
  349.  
  350. New or not pre-defined fieldnames should first be defined for a 
  351. vdata by calling the specify routine VSfdefine.
  352.  
  353.  Return value:  Upon success, 1 is returned; otherwise -1.
  354.  
  355.  
  356. VSsetinterlace
  357. int VSsetinterlace   (vs, interlace)
  358.  
  359.     VDATA    *vs;
  360.     int    interlace;
  361.  
  362. Purpose:  This specify routine sets the interlace type  as specified by 
  363. the argument interlace  for the vdata vs.
  364.  
  365. Specifics:  The interlace may be one of FULL_INTERLACE or 
  366. NO_INTERLACE. This routine applies only to new vdatas attached 
  367. with "w" access. The data is formatted and stored in that vdata 
  368. according to interlace.
  369.  
  370. Return value:  Upon success, 1 is returned; otherwise -1.
  371.  
  372.  
  373. VSsetname
  374. (void) VSsetname   (vs, vsname)
  375.  
  376.     VDATA    *vs;
  377.     char    *vsname;    
  378.  
  379. Purpose:  This specify routine associates the name vsname with the 
  380. vdata vs.
  381.  
  382. Specifics:  Vdatas initially have NULL names, and may be 
  383. renamed more than once. Note that the routine does NOT check for 
  384. uniqueness of vdata names.
  385.  
  386. Routine value:  None.
  387.  
  388.  
  389. VSwrite
  390. int VSwrite   (vs, databuf, nelements, interlace)
  391.  
  392.     VDATA    *vs;
  393.     int    interlace;
  394.     int    nelements;
  395.     unsigned char    *databuf;
  396.  
  397. Purpose:  This is the only write routine of the HDF Vset interface.
  398.  
  399. Specifics:  Given a vdata vs (with "w" access), and a buffer, 
  400. databuf, containing data to be written, this routine will write the 
  401. data from the buffer out to the vdata. 
  402.  
  403. You must specify in nelements, the number of elements╒ worth of 
  404. data to be written, and in interlace  the buffer interlace. (Specify 
  405. either NO_INTERLACE or FULL_INTERLACE).
  406.  
  407. The data in databuf to be written is assumed to be laid out as 
  408. specified by interlace, and has the exact data fields (and order) 
  409. as specified in the last call to VSsetfields  for that vdata.
  410.  
  411.  
  412. It is an error to read from a vdata without first calling 
  413. VSsetfields on that vdata.
  414.  
  415. Note that interlace specifies how the data exists within the user's 
  416. buffer, databuf. If that data is to be stored in a vdata with an 
  417. interlace different from that of the buffer, VSsetinterlace must 
  418. be called prior to VSwrite.
  419.  
  420. Return value:  The routine returns the number of elements read, if 
  421. successful; otherwise, -1 is returned.
  422.  
  423.  
  424.